Add standalone layer-wise KV-cache AutoQuant with forward KL - #2272

What does this PR do?

Type of change: new feature.

Adds standalone layer-wise KV-cache AutoQuantize with isolated forward-KL sensitivity:

• introduces mtq.auto_quantize_kv_cache with one supported K/V format selected per eligible attention layer;
• solves a width-weighted additive recipe under constraints.kv_effective_bits;
• preserves existing non-KV quantizer execution while freezing unrelated calibration state;
• supports persistent/exportable FP8 K/V, NVFP4 K/V, and FP8-K/NVFP4-V candidates;
• saves resumable search state and a JSON-safe sensitivity report;
• exports the exact selected per-layer K/V mapping through unified Hugging Face export; and
• invokes the public API from examples/hf_ptq/hf_ptq.py through a standalone calibration-free recipe.

The implementation is architecture-driven. Plain and conditional-generation Qwen causal attention is supported, hybrid full-attention mixers are discovered through their K/V quantizer boundary, and nonattention/Mamba modules remain outside the search. Ambiguous aliases, unsupported distributed execution, structural algorithms, invalid storage declarations, nonpersistent scales, and unsupported K/V pairs fail closed.

GEMM PTQ/AutoQuantize followed by KV AutoQuantize is intentionally excluded and proposed separately in stacked PR #2273.

Usage

python examples/hf_ptq/hf_ptq.py \
  --pyt_ckpt_path Qwen/Qwen3-1.7B \
  --recipe general/auto_quantize/kv_fp8_nvfp4_cast_kl_div_at_5p4bits \
  --auto_quantize_checkpoint /path/to/kv_autoquant.pth \
  --export_path /path/to/qwen3-1.7b-mixed-kv

Testing

• 364 focused tests passed across KV AutoQuant, recipe loading, unified export, and the actual hf_ptq.py public-API path.
• The shipped standalone recipe runs end to end on a tiny offline Qwen fixture and preserves exportable scale state.
• Changed-file pre-commit hooks passed, including recipe validation, Ruff, mypy, Bandit, Markdown, and YAML checks.

Before your PR is "Ready for review"

• Is this change backward compatible?: ✅
• If you copied code from any other sources or added a new PIP dependency, did you follow guidance in CONTRIBUTING.md: N/A
• Did you write any new necessary tests?: ✅
• Did you update Changelog?: ✅
• Did you get Claude approval on this PR?: ❌ (draft)

Additional Information

• This is split from the combined ground-truth implementation in draft PR Add layer-wise KV-cache AutoQuant with forward KL #2211 to reduce review scope; composition is isolated in Compose GEMM and KV-cache AutoQuant workflows #2273.
• The standalone core tree contains no composed GEMM→KV recipe schema or orchestration.
• Full FP8 K/V and full NVFP4 K/V require a downstream consumer that reads kv_cache_quantized_layers; FP8-K/NVFP4-V additionally requires a compatible asymmetric runtime kernel.